<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>numpy.sort &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <script type="text/javascript" src="../../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../../about.html" >
    <link rel="index" title="Index" href="../../genindex.html" >
    <link rel="search" title="Search" href="../../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../../index.html" >
    <link rel="up" title="Sorting, searching, and counting" href="../routines.sort.html" >
    <link rel="next" title="numpy.lexsort" href="numpy.lexsort.html" >
    <link rel="prev" title="Sorting, searching, and counting" href="../routines.sort.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../../index.html">
      <img border=0 alt="NumPy" src="../../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="../index.html" >NumPy Reference</a></li>
          <li class="active"><a href="../routines.html" >Routines</a></li>
          <li class="active"><a href="../routines.sort.html" accesskey="U">Sorting, searching, and counting</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="numpy.lexsort.html" title="numpy.lexsort"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="../routines.sort.html" title="Sorting, searching, and counting"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="../routines.sort.html"
                        title="previous chapter">Sorting, searching, and counting</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="numpy.lexsort.html"
                        title="next chapter">numpy.lexsort</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="numpy-sort">
<h1>numpy.sort<a class="headerlink" href="#numpy-sort" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="numpy.sort">
<code class="sig-prename descclassname">numpy.</code><code class="sig-name descname">sort</code><span class="sig-paren">(</span><em class="sig-param">a</em>, <em class="sig-param">axis=-1</em>, <em class="sig-param">kind=None</em>, <em class="sig-param">order=None</em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/numpy/numpy/blob/v1.18.1/numpy/core/fromnumeric.py#L837-L990"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#numpy.sort" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a sorted copy of an array.</p>
<dl class="field-list">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl>
<dt><strong>a</strong><span class="classifier">array_like</span></dt><dd><p>Array to be sorted.</p>
</dd>
<dt><strong>axis</strong><span class="classifier">int or None, optional</span></dt><dd><p>Axis along which to sort. If None, the array is flattened before
sorting. The default is -1, which sorts along the last axis.</p>
</dd>
<dt><strong>kind</strong><span class="classifier">{‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, optional</span></dt><dd><p>Sorting algorithm. The default is ‘quicksort’. Note that both ‘stable’
and ‘mergesort’ use timsort or radix sort under the covers and, in general,
the actual implementation will vary with data type. The ‘mergesort’ option
is retained for backwards compatibility.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.15.0.: </span>The ‘stable’ option was added.</p>
</div>
</dd>
<dt><strong>order</strong><span class="classifier">str or list of str, optional</span></dt><dd><p>When <em class="xref py py-obj">a</em> is an array with fields defined, this argument specifies
which fields to compare first, second, etc.  A single field can
be specified as a string, and not all fields need be specified,
but unspecified fields will still be used, in the order in which
they come up in the dtype, to break ties.</p>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl class="simple">
<dt><strong>sorted_array</strong><span class="classifier">ndarray</span></dt><dd><p>Array of the same type and shape as <em class="xref py py-obj">a</em>.</p>
</dd>
</dl>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><a class="reference internal" href="numpy.ndarray.sort.html#numpy.ndarray.sort" title="numpy.ndarray.sort"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ndarray.sort</span></code></a></dt><dd><p>Method to sort an array in-place.</p>
</dd>
<dt><a class="reference internal" href="numpy.argsort.html#numpy.argsort" title="numpy.argsort"><code class="xref py py-obj docutils literal notranslate"><span class="pre">argsort</span></code></a></dt><dd><p>Indirect sort.</p>
</dd>
<dt><a class="reference internal" href="numpy.lexsort.html#numpy.lexsort" title="numpy.lexsort"><code class="xref py py-obj docutils literal notranslate"><span class="pre">lexsort</span></code></a></dt><dd><p>Indirect stable sort on multiple keys.</p>
</dd>
<dt><a class="reference internal" href="numpy.searchsorted.html#numpy.searchsorted" title="numpy.searchsorted"><code class="xref py py-obj docutils literal notranslate"><span class="pre">searchsorted</span></code></a></dt><dd><p>Find elements in a sorted array.</p>
</dd>
<dt><a class="reference internal" href="numpy.partition.html#numpy.partition" title="numpy.partition"><code class="xref py py-obj docutils literal notranslate"><span class="pre">partition</span></code></a></dt><dd><p>Partial sort.</p>
</dd>
</dl>
</div>
<p class="rubric">Notes</p>
<p>The various sorting algorithms are characterized by their average speed,
worst case performance, work space size, and whether they are stable. A
stable sort keeps items with the same key in the same relative
order. The four algorithms implemented in NumPy have the following
properties:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 22%" />
<col style="width: 14%" />
<col style="width: 25%" />
<col style="width: 24%" />
<col style="width: 16%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>kind</p></th>
<th class="head"><p>speed</p></th>
<th class="head"><p>worst case</p></th>
<th class="head"><p>work space</p></th>
<th class="head"><p>stable</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>‘quicksort’</p></td>
<td><p>1</p></td>
<td><p>O(n^2)</p></td>
<td><p>0</p></td>
<td><p>no</p></td>
</tr>
<tr class="row-odd"><td><p>‘heapsort’</p></td>
<td><p>3</p></td>
<td><p>O(n*log(n))</p></td>
<td><p>0</p></td>
<td><p>no</p></td>
</tr>
<tr class="row-even"><td><p>‘mergesort’</p></td>
<td><p>2</p></td>
<td><p>O(n*log(n))</p></td>
<td><p>~n/2</p></td>
<td><p>yes</p></td>
</tr>
<tr class="row-odd"><td><p>‘timsort’</p></td>
<td><p>2</p></td>
<td><p>O(n*log(n))</p></td>
<td><p>~n/2</p></td>
<td><p>yes</p></td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The datatype determines which of ‘mergesort’ or ‘timsort’
is actually used, even if ‘mergesort’ is specified. User selection
at a finer scale is not currently available.</p>
</div>
<p>All the sort algorithms make temporary copies of the data when
sorting along any but the last axis.  Consequently, sorting along
the last axis is faster and uses less space than sorting along
any other axis.</p>
<p>The sort order for complex numbers is lexicographic. If both the real
and imaginary parts are non-nan then the order is determined by the
real parts except when they are equal, in which case the order is
determined by the imaginary parts.</p>
<p>Previous to numpy 1.4.0 sorting real and complex arrays containing nan
values led to undefined behaviour. In numpy versions &gt;= 1.4.0 nan
values are sorted to the end. The extended sort order is:</p>
<blockquote>
<div><ul class="simple">
<li><p>Real: [R, nan]</p></li>
<li><p>Complex: [R + Rj, R + nanj, nan + Rj, nan + nanj]</p></li>
</ul>
</div></blockquote>
<p>where R is a non-nan real value. Complex values with the same nan
placements are sorted according to the non-nan part if it exists.
Non-nan values are sorted as before.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.12.0.</span></p>
</div>
<p>quicksort has been changed to <a class="reference external" href="https://en.wikipedia.org/wiki/Introsort">introsort</a>.
When sorting does not make enough progress it switches to
<a class="reference external" href="https://en.wikipedia.org/wiki/Heapsort">heapsort</a>.
This implementation makes quicksort O(n*log(n)) in the worst case.</p>
<p>‘stable’ automatically chooses the best stable sorting algorithm
for the data type being sorted.
It, along with ‘mergesort’ is currently mapped to
<a class="reference external" href="https://en.wikipedia.org/wiki/Timsort">timsort</a>
or <a class="reference external" href="https://en.wikipedia.org/wiki/Radix_sort">radix sort</a>
depending on the data type.
API forward compatibility currently limits the
ability to select the implementation and it is hardwired for the different
data types.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.17.0.</span></p>
</div>
<p>Timsort is added for better performance on already or nearly
sorted data. On random data timsort is almost identical to
mergesort. It is now used for stable sort while quicksort is still the
default sort if none is chosen. For timsort details, refer to
<a class="reference external" href="https://github.com/python/cpython/blob/3.7/Objects/listsort.txt">CPython listsort.txt</a>.
‘mergesort’ and ‘stable’ are mapped to radix sort for integer data types. Radix sort is an
O(n) sort instead of O(n log n).</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.17.0.</span></p>
</div>
<p>NaT now sorts to the end of arrays for consistency with NaN.</p>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span><span class="mi">4</span><span class="p">],[</span><span class="mi">3</span><span class="p">,</span><span class="mi">1</span><span class="p">]])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>                <span class="c1"># sort along the last axis</span>
<span class="go">array([[1, 4],</span>
<span class="go">       [1, 3]])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>     <span class="c1"># sort the flattened array</span>
<span class="go">array([1, 1, 3, 4])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>        <span class="c1"># sort along the first axis</span>
<span class="go">array([[1, 1],</span>
<span class="go">       [3, 4]])</span>
</pre></div>
</div>
<p>Use the <em class="xref py py-obj">order</em> keyword to specify a field to use when sorting a
structured array:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">dtype</span> <span class="o">=</span> <span class="p">[(</span><span class="s1">&#39;name&#39;</span><span class="p">,</span> <span class="s1">&#39;S10&#39;</span><span class="p">),</span> <span class="p">(</span><span class="s1">&#39;height&#39;</span><span class="p">,</span> <span class="nb">float</span><span class="p">),</span> <span class="p">(</span><span class="s1">&#39;age&#39;</span><span class="p">,</span> <span class="nb">int</span><span class="p">)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">values</span> <span class="o">=</span> <span class="p">[(</span><span class="s1">&#39;Arthur&#39;</span><span class="p">,</span> <span class="mf">1.8</span><span class="p">,</span> <span class="mi">41</span><span class="p">),</span> <span class="p">(</span><span class="s1">&#39;Lancelot&#39;</span><span class="p">,</span> <span class="mf">1.9</span><span class="p">,</span> <span class="mi">38</span><span class="p">),</span>
<span class="gp">... </span>          <span class="p">(</span><span class="s1">&#39;Galahad&#39;</span><span class="p">,</span> <span class="mf">1.7</span><span class="p">,</span> <span class="mi">38</span><span class="p">)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">values</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">dtype</span><span class="p">)</span>       <span class="c1"># create a structured array</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">order</span><span class="o">=</span><span class="s1">&#39;height&#39;</span><span class="p">)</span>                        
<span class="go">array([(&#39;Galahad&#39;, 1.7, 38), (&#39;Arthur&#39;, 1.8, 41),</span>
<span class="go">       (&#39;Lancelot&#39;, 1.8999999999999999, 38)],</span>
<span class="go">      dtype=[(&#39;name&#39;, &#39;|S10&#39;), (&#39;height&#39;, &#39;&lt;f8&#39;), (&#39;age&#39;, &#39;&lt;i4&#39;)])</span>
</pre></div>
</div>
<p>Sort by age, then height if ages are equal:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">order</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;age&#39;</span><span class="p">,</span> <span class="s1">&#39;height&#39;</span><span class="p">])</span>               
<span class="go">array([(&#39;Galahad&#39;, 1.7, 38), (&#39;Lancelot&#39;, 1.8999999999999999, 38),</span>
<span class="go">       (&#39;Arthur&#39;, 1.8, 41)],</span>
<span class="go">      dtype=[(&#39;name&#39;, &#39;|S10&#39;), (&#39;height&#39;, &#39;&lt;f8&#39;), (&#39;age&#39;, &#39;&lt;i4&#39;)])</span>
</pre></div>
</div>
</dd></dl>

</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>